<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Webgraph</title>
  </head>

  <body>

	 <P>Main classes implementing labelling for {@linkplain it.unimi.dsi.webgraph.ImmutableGraph immutable graphs}.
	 A labelled immutable graph is a graph endowed with labels, on its arcs and/or on its nodes; currently, only
	 arc labelling is implemented (since node labelling can be easily dealt with outside of the WebGraph framework, anyway).
	 
	<p><strong>Warning</strong>: this package is experimental.

	 <H1>Labels</H1>
	 
	 <P>A label is just an instance of a class implementing the {@link it.unimi.dsi.webgraph.labelling.Label} interface: essentially,
	 for maximum versatility, is a set of key/value pairs, where keys are strings and values can be essentially anything; in most simple cases,
	 though, labels will be made by a single key/value pair (and the key will be, of course, irrelevant).
	 All arcs of the same graph will have labels of the same class, and for this reason labels offer a {@link it.unimi.dsi.webgraph.labelling.Label#copy()} 
	 method that allows the prototype design pattern to be used.
	 
	 <P>The only requirement for the serialisation of labels is that every label can be written as a self-delimiting bit sequence (via the 
	 {@link it.unimi.dsi.webgraph.labelling.Label#toBitStream(it.unimi.dsi.io.OutputBitStream,int)} method); essentially,
	 two kinds of label exists: fixed-width labels (that write themselves using always the same, fixed number of bits) or
	 variable-width labels; you can know whether a label has fixed width or not by calling {@link it.unimi.dsi.webgraph.labelling.Label#fixedWidth()}
	 (this method will return -1 if the width is variable).
	 
	 <P>As an example, single-attribute integer label classes are implemented, {@linkplain it.unimi.dsi.webgraph.labelling.FixedWidthIntLabel one using fixed width}
	 and {@linkplain it.unimi.dsi.webgraph.labelling.GammaCodedIntLabel another using &gamma;-coding}.
	 
	 <H2>Labelled graphs</H2>
	 
	 <P>An {@linkplain it.unimi.dsi.webgraph.labelling.ArcLabelledImmutableGraph arc-labelled immutable graphs} is an 
	 {@linkplain it.unimi.dsi.webgraph.ImmutableGraph immutable graphs} with labels on its arcs; it rewrites the immutable graphs methods
	 covariantly so that, for example, when one iterates on the successors of a node using {@linkplain it.unimi.dsi.webgraph.labelling.ArcLabelledImmutableGraph#successors(int)}
	 not a simple {@link it.unimi.dsi.fastutil.ints.IntIterator} is returned (iterating over the nodes that are successors of the given node), but rather
	 a {@link it.unimi.dsi.webgraph.labelling.ArcLabelledNodeIterator.LabelledArcIterator} (that returns every time a node/label pair).
	 
	 <P>Even though different implementations of {@linkplain it.unimi.dsi.webgraph.labelling.ArcLabelledImmutableGraph arc-labelled immutable graphs}
	 may exist, we provide one ({@link it.unimi.dsi.webgraph.labelling.BitStreamArcLabelledImmutableGraph}) that assumes that an immutable graph has been
	 provided and that labels have been written onto a label file in the same order as the arcs of the immutable graph would be returned by the 
	 {@link it.unimi.dsi.webgraph.labelling.ArcLabelledImmutableGraph#nodeIterator()} method. An additional offset file must be provided that 
	 allows one to know the offset (in bit) within the label file where the labels of the arcs going out of a given node start.
	 These data are generated using the <code>store()</code> methods whose implementation is suggested in
	 the class documentation of {@linkplain it.unimi.dsi.webgraph.labelling.ArcLabelledImmutableGraph}.

  </body>
</html>
